﻿/*!
 * 定义模块 Inbox (已接收的通知) 中所有功能的服务 API。
 * 
 * Copyright (c), 上海沃恩信息科技有限公司.
 * All rights reserved.
 * Licensed under BSD (https://www.pittypat.work/bsd.html).
 */

/*
 * @param {Object} $    jQuery 命名空间。
 * @param {Object} $$   pittypat 命名空间。
 * @param {Object} _mod 模块 Inbox (已接收的通知) 的命名空间。
 * 
 * 更多说明请参见：
 * https://www.pittypat.work/com/waln/pittypat/coding/help/_api.js.html。
 */
(function ($, $$, _mod) {
    'use strict';

    // 模块的 API 和 UI 命名空间
    var _api = _mod.api = _mod.api || {};

	/*
	 * 功能 List (通知列表) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // 页码
	 *     pageIndex: {int64?},
	 * 
	 *     // 页面尺寸
	 *     pageSize: {int64?},
	 * 
	 *     // 排序名称
	 *     orderName: {string(30)?},
	 * 
	 *     // 排序方向
	 *     orderDirection: {string(4)?},
	 * 
	 *     // 通知标题
	 *     // 通知的标题。
	 *     title: {string(50)?},
	 * 
	 *     // 发送人名称
	 *     // 消息发送人的名称。
	 *     senderName: {string(50)?},
	 * 
	 *     // 是否已读
	 *     // 查询已读或者未读的通知。
	 *     isRead: {bool?},
	 * 
	 *     // 紧急程度
	 *     // 通知的紧急程度代码：1-常规，2-紧急，4-特急。默认为常规（1）。
	 *     urgency: {int8?},
	 * 
	 *     // 分组
	 *     // 通知隶属的分组。
	 *     group: {string(30)?},
	 * 
	 *     // 起始接收时间
	 *     // 消息的接收时间。
	 *     receiveTimeFrom: {datetime?},
	 * 
	 *     // 截至接收时间
	 *     // 消息的接收时间。
	 *     receiveTimeTo: {datetime?},
	 * 
	 *     // 是否包含置顶通知
	 *     // 指示是否同时查询置顶的通知消息。
	 *     includesTop: {bool?} 
	 * }
	 * 
	 * 输出(success.result):
	 * {
	 *     // 总行数
	 *     totalRows: {int64?},
	 * 
	 *     // 未置顶通知列表
	 *     // 满足条件的未置顶通知列表。
	 *     notifications: [{
	 *         // Id
	 *         // 消息的 Id。
	 *         id: {uuid?},
	 * 
	 *         // 发送用户的 Id
	 *         // 发送消息的用户的 Id，如果是系统消息，则为 null。
	 *         senderId: {uuid?},
	 * 
	 *         // 发送人名称
	 *         // 消息发送人的名称。
	 *         senderName: {string?},
	 * 
	 *         // 发送人头像路径
	 *         // 消息发送人头像文件的路径。
	 *         senderFaceUrl: {string?},
	 * 
	 *         // 接收用户的 Id
	 *         // 接收消息的用户的 Id，如果是广播消息，则为 null。
	 *         receiverId: {uuid?},
	 * 
	 *         // 接收时间
	 *         // 消息的接收时间。
	 *         receiveTime: {datetime?},
	 * 
	 *         // 阅读时间
	 *         // 接收人阅读通知的时间，如果尚未阅读，为 null。
	 *         readTime: {datetime?},
	 * 
	 *         // 置顶时间
	 *         // 将通知消息置顶的时间。
	 *         topTime: {datetime?},
	 * 
	 *         // 紧急程度
	 *         // 通知的紧急程度代码：1-常规，2-紧急，4-特急。默认为常规（1）。
	 *         urgency: {int8?},
	 * 
	 *         // 分组
	 *         // 通知隶属的分组。
	 *         group: {string?},
	 * 
	 *         // 通知标题
	 *         // 通知的标题。
	 *         title: {string?},
	 * 
	 *         // 通知消息摘要
	 *         // 对通知消息正文的摘要信息。
	 *         summary: {string?},
	 * 
	 *         // 正文类型代码
	 *         // 消息正文类型代码：1-纯文本，2-HTML。
	 *         bodyType: {int8?},
	 * 
	 *         // 目标功能路径
	 *         // 点击消息时要进入的路径。
	 *         funcUrl: {string?},
	 * 
	 *         // 附件 Id
	 *         // 通知消息的附件文件的数目。
	 *         attachmentId: {uuid?},
	 * 
	 *         // 附件文件路径
	 *         // 附近文件的虚拟路径。
	 *         attachmentUrl: {string?},
	 * 
	 *         // 附件文件名称
	 *         // 附件文件的名称，包含扩展名称。
	 *         attachmentName: {string?} 
	 *     }, ...],
	 * 
	 *     // 置顶通知列表
	 *     // 已经被用户置顶的通知消息的列表。置顶通知列表不会进行分页。
	 *     topNotifications: [{
	 *         // Id
	 *         // 消息的 Id。
	 *         id: {uuid?},
	 * 
	 *         // 发送用户的 Id
	 *         // 发送消息的用户的 Id，如果是系统消息，则为 null。
	 *         senderId: {uuid?},
	 * 
	 *         // 发送人名称
	 *         // 消息发送人的名称。
	 *         senderName: {string?},
	 * 
	 *         // 发送人头像路径
	 *         // 消息发送人头像文件的路径。
	 *         senderFaceUrl: {string?},
	 * 
	 *         // 接收用户的 Id
	 *         // 接收消息的用户的 Id，如果是广播消息，则为 null。
	 *         receiverId: {uuid?},
	 * 
	 *         // 接收时间
	 *         // 消息的接收时间。
	 *         receiveTime: {datetime?},
	 * 
	 *         // 阅读时间
	 *         // 接收人阅读通知的时间，如果尚未阅读，为 null。
	 *         readTime: {datetime?},
	 * 
	 *         // 置顶时间
	 *         // 将通知消息置顶的时间。
	 *         topTime: {datetime?},
	 * 
	 *         // 紧急程度
	 *         // 通知的紧急程度代码：1-常规，2-紧急，4-特急。默认为常规（1）。
	 *         urgency: {int8?},
	 * 
	 *         // 分组
	 *         // 通知隶属的分组。
	 *         group: {string?},
	 * 
	 *         // 通知标题
	 *         // 通知的标题。
	 *         title: {string?},
	 * 
	 *         // 通知消息摘要
	 *         // 对通知消息正文的摘要信息。
	 *         summary: {string?},
	 * 
	 *         // 正文类型代码
	 *         // 消息正文类型代码：1-纯文本，2-HTML。
	 *         bodyType: {int8?},
	 * 
	 *         // 目标功能路径
	 *         // 点击消息时要进入的路径。
	 *         funcUrl: {string?},
	 * 
	 *         // 附件 Id
	 *         // 通知消息的附件文件的数目。
	 *         attachmentId: {uuid?},
	 * 
	 *         // 附件文件路径
	 *         // 附近文件的虚拟路径。
	 *         attachmentUrl: {string?},
	 * 
	 *         // 附件文件名称
	 *         // 附件文件的名称，包含扩展名称。
	 *         attachmentName: {string?} 
	 *     }, ...]
	 * }
	 */
    _api.list = $$.api({
        // 请求路径
        url: '~/waln/notifying/inbox/list',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'POST',

        // 对 args 进行验证
        validate: function (e) {
            if (!e.args) {
                e.message = '没有提供任何参数。';
                return;
            }

            // 验证 pageIndex (页码)
            if (!$$.util.is.int(e.args.pageIndex, 1, Number.MAX_SAFE_INTEGER)) {
                e.args.pageIndex = 1; // 默认页码 1
            }

            // 验证 pageSize (页面尺寸)
            if (!$$.util.is.int(e.args.pageSize, 1, 1000)) {
                e.args.pageSize = 20; // 默认页面尺寸 20
            }

            // 验证 orderName (排序名称)
            if (!$$.util.is.identifier(e.args.orderName)) {
                e.args.orderName = 'receivetime'; // 默认排序名称
            }

            // 验证 orderDirection (排序方向)
            if (!$$.util.is.orderDirection(e.args.orderDirection)) {
                e.args.orderDirection = 'desc'; // 默认排序方向
            }
            
            // 验证 includesTop (是否包含置顶通知)
            if (!$$.util.is.bool(e.args.includesTop)) {
                e.args.includesTop = true;
            }

            // 空字符串表示通过验证
            e.message = '';
        },

        // 发送给服务器的数据
        data: function (e) {
            e.data = e.args;
        }
    });

	/*
	 * 功能 Details (详细信息) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // Id
	 *     // 消息的 Id。
	 *     id: {uuid?} 
	 * }
	 * 
	 * 输出(success.result):
	 * {
	 *     // 通知正文内容
	 *     // 通知的完整正文内容。
	 *     body: {string(200000)?},
	 * 
	 *     // 附件
	 *     // 目标通知的附件文件。
	 *     attachment: {
	 *         // Id
	 *         // 附件文件的 Id。
	 *         id: {uuid?},
	 * 
	 *         // 文件名称
	 *         // 附件文件的名称，包含扩展名称。
	 *         name: {string?},
	 * 
	 *         // MIME 类型
	 *         // 附件文件的 MIME 类型。
	 *         mime: {string?},
	 * 
	 *         // 附件文件的大小
	 *         // 附件文件的大小，单位：字节。
	 *         size: {int64?},
	 * 
	 *         // 文件路径
	 *         // 附近文件的虚拟路径。
	 *         url: {string?},
	 * 
	 *         // 上传人的 Id
	 *         // 上传了当前附件文件的用户的 Id。
	 *         uploaderId: {uuid?},
	 * 
	 *         // 上传时间
	 *         // 上传当前附件文件的时间。
	 *         uploadTime: {datetime?} 
	 *     },
	 * 
	 *     // 阅读时间
	 *     // 接收人阅读通知的时间，如果尚未阅读，为 null。
	 *     readTime: {datetime?}
	 * }
	 */
    _api.details = $$.api({
        // 请求路径
        url: '~/waln/notifying/inbox/details',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'POST',

        // 对 args 进行验证
        validate: function (e) {
            // 验证 id
            if (!$$.util.is.uuid(e.args)) {
                e.message = '没有提供有效的Id。';
                return;
            }

            // 空字符串表示通过验证
            e.message = '';
        },

        // 发送给服务器的数据
        data: function (e) {
            e.data = {
                // Id
                id: e.args
            };
        }
    });

	/*
	 * 功能 Read (标记为已读) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // Id
	 *     // 消息的 Id。
	 *     id: {uuid?},
	 * 
	 *     // 是否已读
	 *     // 是否将目标通知设置为已读。
	 *     isRead: {bool?} 
	 * }
	 * 
	 * 输出(success.result):
	 * // 阅读时间
	 * // 接收人阅读通知的时间，如果尚未阅读，为 null。
	 * readTime: {datetime?}
	 */
    _api.read = $$.api({
        // 请求路径
        url: '~/waln/notifying/inbox/read',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'POST',

        // 对 args 进行验证
        validate: function (e) {
            if (!e.args) {
                e.message = '没有提供任何参数。';
                return;
            }

            // 验证 id (Id)
            if (!$$.util.is.uuid(e.args.id)) {
                e.message = '没有提供有效的Id。';
                return;
            }

            // 验证 isRead (是否已读)
            if (!$$.util.is.bool(e.args.isRead)) {
                e.message = '没有提供有效的是否已读。';
                return;
            }

            // 空字符串表示通过验证
            e.message = '';
        },

        // 发送给服务器的数据
        data: function (e) {
            e.data = e.args;
        }
    });

	/*
	 * 功能 Top (置顶) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // Id
	 *     // 消息的 Id。
	 *     id: {uuid?},
	 * 
	 *     // 是否置顶
	 *     // 是否将目标通知置顶。
	 *     isTop: {bool?} 
	 * }
	 * 
	 * 输出(success.result):
	 * // 置顶时间
	 * // 将通知消息置顶的时间。
	 * topTime: {datetime?}
	 */
    _api.top = $$.api({
        // 请求路径
        url: '~/waln/notifying/inbox/top',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'POST',

        // 对 args 进行验证
        validate: function (e) {
            if (!e.args) {
                e.message = '没有提供任何参数。';
                return;
            }

            // 验证 id (Id)
            if (!$$.util.is.uuid(e.args.id)) {
                e.message = '没有提供有效的Id。';
                return;
            }

            // 验证 isTop (是否置顶)
            if (!$$.util.is.bool(e.args.isTop)) {
                e.message = '没有提供有效的是否置顶。';
                return;
            }

            // 空字符串表示通过验证
            e.message = '';
        },

        // 发送给服务器的数据
        data: function (e) {
            e.data = e.args;
        }
    });

	/*
	 * 功能 Delete (删除通知) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // 通知 Id 的列表
	 *     // 要被删除的通知消息的 Id 列表，多个之间使用 ',' 分隔。
	 *     ids: {string(4000)?} 
	 * }
	 * 
	 * 输出(success.result):
	 * // 附件文件路径列表
	 * // 被删除通知对应的附件文件的路径列表，用于删除对应的物理文件。
	 * attachmentUrls: {string(300000)?}
	 */
    _api.delete = $$.api({
        // 请求路径
        url: '~/waln/notifying/inbox/delete',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'POST',

        // 对 args 进行验证
        validate: function (e) {
            // 验证 ids
            if (!e.args) {
                e.message = '没有提供有效的通知 Id 的列表。';
                return;
            }

            // 空字符串表示通过验证
            e.message = '';
        },

        // 发送给服务器的数据
        data: function (e) {
            e.data = {
                // 通知 Id 的列表
                ids: e.args
            };
        }
    });
})(jQuery, pittypat, pittypat.namespace('waln.notifying.inbox'));
